Methods

On this page:

Workflow Engine

Deprecations in WorkFlowEngine

Deprecations in WorkFlowEngine are shown in the table below.

Item Description Deprecation Release Removal Release Replacement
returnCompletedTaskData Completes a task and returns the updated job. 2020.1 2021.1 /workflow_engine/finishTask
getJobDeep Get active job details. 2020.2 2021.1 GET /workflow_engine/job/:job_id/details and POST /workflow_engine/tasks/search
getTaskIterations Get job task iterations. 2020.2 2021.2 POST /workflow_engine/tasks/search
addWatchers Add watchers to a job. 2021.2 2022.2 POST /operations-manager/jobs/:jobId/watch
cancelJob Cancel a job. 2021.2 2022.2 POST /operations-manager/jobs/cancel
claimTask Claim a manual task. 2021.2 2022.2 POST /operations-manager/tasks/:id/claim
continueJob Continues a job at a task using the finish state of the last iteration. 2021.2 2022.2 POST /operations-manager/tasks/:id/continue
createJobGroupEntry Add a group to a job. 2021.2 2022.2 POST /operations-manager/jobs/:id/groups
deleteJobGroups Delete all groups for a job. 2021.2 2022.2 PUT /operations-manager/jobs/:id/groups
find Find job documents. 2021.2 2022.2 GET /operations-manager/jobs
findForwardPaths Find the paths between two tasks in a workflow. 2021.2 2022.2 N/A
finishManualTask Completes a manual task. 2021.2 2022.2 POST /operations-manager/jobs/:jobId/tasks/:taskId/finish
fixJob Revert an errored job. 2021.2 2022.2 POST /operations-manager/jobs/:id/revert
getAllLoopTasks Get all loop tasks. 2021.2 2022.2 N/A
getAssociatedJobs Get associated jobs. 2021.2 2022.2 GET /operations-manager/jobs
getEntireJob Get the entire data of a job. 2021.2 2022.2 GET /operations-manager/jobs
getManualTaskController Get the controller of a manual task. 2021.2 2022.2 GET /operations-manager/jobs/:jobId/tasks/:taskId/manual-controller
getJob Get a job. 2021.2 2022.2 GET /operations-manager/jobs/:id
getJobDetails Get details of an active job. 2021.2 2022.2 GET /operations-manager/jobs/:id
getJobFromTaskQuery Get job from a task query. 2021.2 2022.2 GET /operations-manager/tasks?dereference=job
getJobList Get a list of jobs by status. 2021.2 2022.2 GET /operations-manager/jobs
getJobOutput Get the output of a completed job. 2021.2 2022.2 GET /operations-manager/job/:id?dereference=output&include=output
getJobShallow Get shallow data of a job. 2021.2 2022.2 GET /operations-manager/jobs/:id
getJobVisualizationData Get the visualization data of a job. 2021.2 2022.2 N/A
getTask Get a tasks. 2021.2 2022.2 GET /operations-manager/tasks
getTaskStatuses Get the status of each task in a job. 2021.2 2022.2 GET /operations-manager/tasks?equals[job._id]=
listJobGroups List the groups that have access to a job. 2021.2 2022.2 GET /operations-manager/jobs?dereference=groups&include=groups instead
pauseJob Pause a job. 2021.2 2022.2 POST /operations-manager/jobs/pause
prepareMetricsLogs Prepare the metrics logs tarball. 2021.2 2022.2 N/A
queryJobs Get jobs matching the query. 2021.2 2022.2 GET /operations-manager/jobs
queryTasksBrief Get brief information about tasks from the tasks collection. 2021.2 2022.2 GET /operations-manager/tasks
releaseTask Release a manual task. 2021.2 2022.2 POST /operations-manager/tasks/:id/release
removeJobGroup Remove a group from the list of authorized groups for a job. 2021.2 2022.2 DELETE /operations-manager/jobs/:jobId/groups/:groupId
replaceJobGroups Overwrite the list of groups that have access to a job. 2021.2 2022.2 PUT /operations-manager/jobs/:id/groups
resumeJob Resume a paused or errored job. 2021.2 2022.2 POST /operations-manager/jobs/resume
retryTask Retries a task with new variables. 2021.2 2022.2 POST /operations-manager/jobs/:jobId/tasks/:taskId/retry
revertToTask Revert a job from the current task to the target task. 2021.2 2022.2 POST /operations-manager/jobs/:id/revert
searchJobs Search jobs. 2021.2 2022.2 GET /operations-manager/jobs
searchTasks Search tasks. 2021.2 2022.2 GET /operations-manager/tasks
startJobWithOptions Initiate a job in a workflow with options. 2021.2 2022.2 POST /operations-manager/jobs/start
unwatchJob Unwatch a job. 2021.2 2022.2 POST /operations-manager/jobs/:jobId/unwatch
validateAllLoops Validate all loops. 2021.2 2022.2 N/A
watchJob Watch a job. 2021.2 2022.2 POST /operations-manager/jobs/:jobId/watch


Starting Jobs with Incorrect DataTypes

When starting a job with variables, users will no longer be able to input incorrect values for those variables. For example, let's take a simple automation like this one below.

Figure 1: Example Automation

Automation with Variables

The correct types for the job variables are pictured below. Notice the form_name should be a string, resembling "this is a string", and the instance_data should be an object, resembling { "key": "data" }.

Figure 2: Input Job Variables

Job Variable Types

With the example below, the variables are set incorrectly, where an object is used for the form_name and a string for the instance_data.

Figure 3: Set Variables

Bad Variable Types

Even with the incorrect variable types that were supplied, the automation will actually run when the user clicks Start.

Figure 4: Run Automation

Ran Automation

Beginning with IAP 2020.2, however, the system will now display a warning message (at the bottom) to alert users they have given the job incorrect variables.

Figure 5: Warning Message for Incorrect Input Types

Warning Message


What should I do?

At a minimum of two releases from IAP 2020.2, this automation will no longer run if the job variable inputs do not match the type defined in the task. Begin now to modify your task input behavior to only start jobs with the correct input types for job variables so that once it becomes required, it will not impact your operations.

Item Description Deprecation Release Removal Release Replacement
startJobWithOptions Users will no longer be able to pass in values for job variables if the supplied value does not match the type (string, number, object, array, boolean, null) where the job variable is used.
Note: If the value passed in is undefined, it processed as type null.
2020.2 2021.2 N/A


Replacement for Activate Property within Service Config Layer

Workfow Engine will no longer support the activate property within its service_config. Currently, this property allows a specific configuration of the Workflow Engine application to allow or disallow working tasks upon startup. The replacement for this call is the processTasksOnStart property that exists in the properties.json. The replacement property can be set to true to allow working tasks on a specific server on startup, or it can be set to false to disallow working tasks on startup. See sample configuration below.

One special case is if a job is started via child job and passes in a value of undefined for a variable. This will be processed as type null instead of being processed with an undefined type.

Item Description Deprecation Release Removal Release Replacement
activate (service_config property) Establishes if the Workflow Engine task worker is active on startup; this will no longer be determined at the service_config layer. 2021.1 2022.1 processTasksOnStart (properties.json property)

Sample configuration in properties.json

{
  "processTasksOnStart" : false ,
  "pathProps": {
    "description": "File Path Variables",
    "sdk_dir": "/opt/pronghorn-applications",
    "encrypted": true
  },
  "id": "profile1",
  "mongoProps": {
    "credentials": {
      "passwd": "itentialPassword",
      "user": "itentialUser"
    },
    "db": "pronghorn",
    "url": "mongodb://localhost:27017"
  }
}

Structural changes in API responses between Operations Manager (OM) and Workflow Engine (WFE) APIs

With the jobs and tasks APIs moving to Operations Manager (OM), there are some differences from the Workflow Engine (WFE) APIs they replace which will need to be considered for any usage of these APIs. The differences include both the parameters these methods expect and the responses they return.

In general, Operations Manager responses are formatted with a uniform top level structure; all responses will be objects with the following keys: message, data, and metadata.

Key Description
message This property will always be populated with a human readable string. This exists for debugging purposes, as well as proxying actionable feedback to a human user.
data This property will contain any data relevant to the method response, such as a list of jobs, or the result of some action, but is not necessary for every context. In situations where data is not meaningful, it will be set to null.
metadata This property is used as a container for descriptive data. It is used for things like pagination data in a search API, as well as more detailed context for errors such as input validation failures. If a response has no metadata, the key will be set to an empty object ({}).

Differences between WFE and OM equivalent methods

This section details the WFE methods that have been proxied and/or replaced in Operations Manager (OM), along with the success and error responses that are returned.

WFE Method OM Equivalent Method
POST /cancelJob { job_id } POST /jobs/cancel { jobIds } (limits jobIds to length <= 100)
POST /pauseJob { job_id } POST /jobs/pause { jobIds } (limited to 100 jobs)
POST /resumeJob { job_id } POST /jobs/resume { jobIds } (limited to 100 jobs)

Success response:

WFE: Full updated job document

OM: { message: <success-message>, data: null, metadata: {} }
If you consume the updated job document from WFE cancel/pause/resume, perform a second API call in OM to get the updated jobs: GET /jobs?in[_id]=_id1,_id2,...

Error response:

WFE: String message with response code 500

OM: { message: <error-message>, data: null, metadata: {} } with response code 400 for bad data, 401 for unauthorized, and 500 for internal error.


WFE Method OM Equivalent Method
POST /tasks/claim { task_id, user } POST /tasks/:id/claim
and
POST /tasks/:id/assign { userId }

Success response:

WFE: Updated task document

OM: { message: <success-message>, data: null, metadata: {} }
If you depend on the updated task document, perform a second API call in OM to get the updated task: GET /tasks/:id

Error response:

WFE: String message with response code 500

OM: { message: <error-message>, data: null, metadata: {} } with response code 400 for bad data, 401 for unauthorized, and 500 for internal error.


WFE Method OM Equivalent Method
POST /tasks/release { task_id } POST /tasks/:id/release

Success response:

WFE: Updated task document provided at the root of the response

OM: { message: <success-message>, data: null, metadata: {} }
If you depend on the updated task document, perform a second API call in OM to get the updated task: GET /tasks/:id

Error response:

WFE: String message with response code 500

OM: { message: <error-message>, data: null, metadata: {} } with response code 400 for bad data, 401 for unauthorized, and 500 for internal error


WFE Method OM Equivalent Method
GET /jobs/:id/groups GET /jobs?dereference=groups&include=groups
DELETE /jobs/:id/groups/:group DELETE /jobs/:jobId/groups/:groupId
PUT /jobs/:id/groups PUT /jobs/:id/groups
POST /jobs/:id/groups { group } POST /jobs/:id/groups { groupId }
DELETE /jobs/:id/groups DELETE /jobs/:id/groups

Success response:

WFE: Boolean indicating success or failure

OM: { message: <success-message>, data: null, metadata: {} }

Error response:

WFE: String message with response code 500

OM: { message: <error-message>, data: null, metadata: {} } with response code 400 for bad data, 401 for unauthorized, and 500 for internal error.


WFE Method OM Equivalent Method
POST /jobs/:jobId/continueJob { jobId, taskId } POST /jobs/:id/continue { taskId }

Success response:

WFE: Updated job document

OM: { message: <success-message>, data: null, metadata: {} }
If you depend on the updated job document, perform a second API call to get the updated job: GET /jobs/:jobId

Error response:

WFE: String message with response code 500

OM: { message: <error-message>, data: null, metadata: {} } with response code 400 for bad data, 401 for unauthorized, and 500 for internal error.


WFE Method OM Equivalent Method
POST /fixJob { job_id, errored_task, revert_task } POST /jobs/:id/revert { fromTask, toTask }

Success response:

WFE: Updated job document

OM: { message: <success-message>, data: null, metadata: {} }
If you depend on the updated job document, perform a second API call to get the updated job: GET /jobs/:jobId

Error response:

WFE: String message with response code 500

OM: { message: <error-message>, data: null, metadata: {} } with response code 400 for bad data, 401 for unauthorized, and 500 for internal error.


WFE Method OM Equivalent Method
DELETE /job/:job_id/watch POST /jobs/:id/unwatch
PUT /job/:job_id/watch POST /jobs/:id/watch

Success response:

WFE: Username of the user added to the watchers list is provided at the root of the response.

OM:

{
  message: <success-message>,
  data: null,
  metadata: {}
}

Error response:

WFE: String message with 500 response code

OM: { message: <error-message>, data: null, metadata: {} } with response code 400 for bad inputs and 500 for internal error.


WFE Method OM Equivalent Method
POST /jobs/:jobId/retryTask { taskId, variables } POST jobs/:jobId/tasks/:taskId/retry { variables }

Success response:

WFE: Updated job document provided at the root of the response

OM: { message: <success-message>, data: null, metadata: {} }
If you depend on the updated job document, perform a second API call in OM to get the updated job: GET /jobs/:id

Error response:

WFE: String message with response code 500

OM: { message: <error-message>, data: null, metadata: {} } with response code 400 for bad data, 401 for unauthorized, and 500 for internal error.


WFE Method OM Equivalent Method
POST /finishTask { job_id, task_id } POST jobs/:jobId/tasks/:taskId/finish { finish_state, variables }

Success response:

WFE: Updated job document

OM: { message: <success-message>, data: null, metadata: {} }
If you depend on the updated job document, perform a second API call to get the updated job: GET /jobs/:jobId

Error response:

WFE: String message with response code 500

OM: { message: <error-message>, data: null, metadata: {} } with response code 400 for bad data, 401 for unauthorized, and 500 for internal error.


WFE Method OM Replacement Method
POST /jobs/find { query, options } GET /jobs

Note on querying: The replacement call uses a query parameter based searching interface rather than one based on JSON in the post body. Refer to the associated docs for more details.

Success response:

WFE: [{ ...job1 }, { ...job2 }, ...]
Array of job documents returned at the root of the response

OM:

{
  message: <success-message>,
  data: [...jobs],
  metadata: {
    "skip": <number>,
    "limit": <number>,
    "nextPageSkip": <null | number>,
    "previousPageSkip": <null | number>,
    "total": <number>,
    "currentPageSize": <number>,
  }
}

Error response:

WFE: String message with response code 500

OM: { message: <error-message>, data: null, metadata: {} } with response code 400 for bad inputs and 500 for internal error.


WFE Method OM Replacement Method
POST /getAssociatedJobs { options } GET /jobs?exclude=transitions,variables&dereference=accounts.metrics.user + Search terms equivalent to options.filter

Notes:

  • On querying: POST /getAssociatedJobs supports filtering via options.filter. Refer to the OM search API documentation on details related to filtering with GET /jobs

  • On pagination: POST /getAssociatedJobs options.skip and options.limit become ?skip=...&limit=... in GET /jobs

Success response:

WFE:

{
  results: [...searchResults],
  skip: <number>,
  limit: <number>,
  total: <number>
}

OM:

{
  message: <success-message>,
  data: [...searchResults],
  metadata: {
    skip: <number>,
    limit: <number>,
    nextPageSkip: <null | number>,
    previousPageSkip: <null | number>,
    total: <number>,
    currentPageSize: <number>,
    }
}

Error response:

WFE: String message with response code 500

OM: { message: <error-message>, data: null, metadata: {} } with response code 400 for bad inputs and 500 for internal error.


WFE Method OM Replacement Method
GET /getEntireJob/:job_data GET /jobs/:id?dereference=tasks

Success response:

WFE: Job document is returned at the root of the response

OM:

{
  message: <success-response>,
  data: <job>,
  metadata: {}
}

Error response:

WFE: String message with response code 500

OM: { message: <error-message>, data: null, metadata: {} } with response code 400 for bad inputs and 500 for internal error.


WFE Method OM Replacement Method
GET /getJob/:job_id GET /jobs/:id

Success response:

WFE: Job document is returned at the root of the response

OM:

{
  message: <success-response>,
  data: <job>,
  metadata: {}
}

Error response:

WFE: String message with response code 500

OM: { message: <error-message>, data: null, metadata: {} } with response code 400 for bad inputs and 500 for internal error.


WFE Method OM Replacement Method
GET /job/:job_id/details GET /jobs/:id

Success response:

WFE: Job document is returned at the root of the response

OM:

{
  message: <success-response>,
  data: <job>,
  metadata: {}
}

Error response:

WFE: String message with response code 500

OM: { message: <error-message>, data: null, metadata: {} } with response code 400 for bad inputs and 500 for internal error.


WFE Method OM Replacemment Method
POST /getJobFromTaskQuery { task_query, options } GET /tasks?dereference=job&<…search-params>

Success response:

WFE:

{
  results: [...jobDocuments],
  skip: <number>,
  limit: <number>,
  total: <number>
}

OM: 

Overall response

{
  message: <success-message>,
  data: [...taskDocumentsWithJobs],
  metadata: {
    skip: <number>,
    limit: <number>,
    nextPageSkip: <null | number>,
    previousPageSkip: <null | number>,
    total: <number>,
    currentPageSize: <number>,
  }
}

Individual task documents
- Note the difference in job document location with the WFE method.

{
  ...ordinaryTaskData,
  job: <complete-parent-job-document>
}

Note on output: Whereas the WFE method returns only jobs themselves as output, the OM replacement method will return tasks at the top level, with jobs nested within the tasks. There is not a direct way to get a list of just the unique jobs returned by this query; this is up to the API caller to implement.

Error response:

WFE: String message with 500 response code

OM: { message: <error-message>, data: null, metadata: {} } with response code 400 for bad inputs and 500 for internal error.


WFE Method OM Replacement Method
POST /getJobList/:status { options } GET /jobs?equals[status]=

Success response:

WFE:

{
  results: [...jobDocuments],
  skip: <number>,
  limit: <number>,
  total: <number>
}

OM:

{
  message: <success-message>,
  data: [...jobDocuments],
  metadata: {
    skip: <number>,
    limit: <number>,
    nextPageSkip: <null | number>,
    previousPageSkip: <null | number>,
    total: <number>,
    currentPageSize: <number>,
  }
}

Error responses:

WFE: String message with 500 response code

OM: { message: <error-message>, data: null, metadata: {} } with response code 400 for bad inputs and 500 for internal error.


WFE Method OM Replacement Method
GET /job/:job_id/output GET /job/:id?dereference=output&include=output,variables

Success response:

WFE: Raw job output is included at the root of the document. This output is from the workflow's output schema, if it exists; otherwise it is just the current state of the jobs variables.

OM:

{
  message: <success-message>,
  data: {
    output: <null | job-output>,
    variables: <job-variables>
  },
  metadata: {}
}

Error response:

WFE: String message with 500 response code

OM: { message: <error-message>, data: null, metadata: {} } with response code 400 for bad inputs and 500 for internal error.


WFE Method OM Replacement Method
GET /getJobShallow/:job_data GET /job/:id?exclude=variables&dereference=tasks

Success response:

WFE: Job is included at the root of the response

OM:

{
  message: <success-message>,
  data: <job-document>,
  metadata: {}
}

Error response:

WFE: String message with 500 response code

OM: { message: <error-message>, data: null, metadata: {} } with response code 400 for bad inputs and 500 for internal error.


WFE Method OM Proxy Method
GET /tasks/controller/job/:jobId/task/:taskId GET /jobs/:jobId/tasks/:taskId/manual-controller

Success response:

WFE: Manual task controller is returned at the root of the response

OM:

{
  message: <success-message>,
  data: <manual-task-controller>,
  metadata: {}
}

Error response:

WFE: String message with 500 response code

OM: { message: <error-message>, data: null, metadata: {} } with response code 400 for bad inputs, 401 for unauthorized, and 500 for internal error.


WFE Method OM Replacement Method
POST /getTask { query, filter } GET /tasks?limit=1&include=<…fields-from-filter>

Note on the filter parameter: The Workflow Engine POST /getTask uses the filter parameter to specify which fields to include in the response. To construct an equivalent include expression, please refer to projection section of the OM search API documentation and use the keys of your filter parameter as values in both the include and exclude.

Success responses:

WFE: Task document provided in the root of the response

OM:

{
  message: <success-message>,
  data: <task-document>,
  metadata: {}
}

Error response:

WFE: String message with 500 response code

OM: { message: <error-message>, data: null, metadata: {} } with response code 400 for bad inputs, 401 for unauthorized, and 500 for internal error.


WFE Method OM Replacement Method
GET /getTaskIterations/:job_id/:task GET /job/:id?dereference=tasks&include=tasks..iterations

Success response:

WFE: [{ ...task1 }, { ...task2 }, ...]

OM:

{
  message: <success-message>,
  data: {
    tasks: {
      [<task-id>]: {
        iterations: [
          { ...task1 },
          { ...task2 },
          ...
        ]
      }
    }
  },
  metadata: {}
}

Error response:

WFE: String message with 500 response code

OM: { message: <error-message>, data: null, metadata: {} } with response code 400 for bad inputs, 401 for unauthorized, and 500 for internal error.


WFE Method OM Replacement Method
GET /job/statuses/:job_id GET /tasks?equals[job._id]=&equals[job.task]=&include=status&dereference=accounts.metrics.owner

Success response:

WFE: Full task documents are provided at the root of the response

OM:

{
  message: <success-message>,
  data: [...taskDocuments],
  metadata: {
    skip: <number>,
    limit: <number>,
    nextPageSkip: <null | number>,
    previousPageSkip: <null | number>,
    total: <number>,
    currentPageSize: <number>,
  }
}

Error response:

WFE: String message with 500 response code

OM: { message: <error-message>, data: null, metadata: {} } with response code 400 for bad inputs and 500 for internal error.


WFE Method OM Replacement Method
POST /queryJobs GET /jobs

⚠ Please use the OM search API documentation as a reference when translating queries provided to POST /queryJobs into query parameters to GET /jobs.

Success response:

WFE: [{ ...job1 }, { ...job2 }, ...]

OM:

{
  message: <success-message>,
  data: [{ ...job1 }, { ...job2 }, ...],
  metadata: {
    skip: <number>,
    limit: <number>,
    nextPageSkip: <null | number>,
    previousPageSkip: <null | number>,
    total: <number>,
    currentPageSize: <number>,
  }
}

Error response:

WFE: String message with 500 response code

OM: { message: <error-message>, data: null, metadata: {} } with response code 400 for bad inputs and 500 for internal error.


WFE Method OM Replacement Method
POST /queryTasksBrief GET /tasks?exclude=variables

Success response:

WFE: [{ ...task1 }, { ...task2 }, ...]

OM:

{
  message: <success-message>,
  data: [{ ...task1 }, { ...task2 }, ...],
  metadata: {
    skip: <number>,
    limit: <number>,
    nextPageSkip: <null | number>,
    previousPageSkip: <null | number>,
    total: <number>,
    currentPageSize: <number>,
  }
}

Error response:

WFE: String message with 500 response code

OM: { message: <error-message>, data: null, metadata: {} } with response code 400 for bad inputs and 500 for internal error.


WFE Method OM Replacement Method
POST /jobs/search GET /jobs

⚠ Please use the OM search documentation as a reference when translating search parameters between these two endpoints.

Success response:

WFE: [{ ...job1 }, { ...job2 }, ...]

OM:

{
  message: <success-message>,
  data: [{ ...job1 }, { ...job2 }, ...],
  metadata: {
    skip: <number>,
    limit: <number>,
    nextPageSkip: <null | number>,
    previousPageSkip: <null | number>,
    total: <number>,
    currentPageSize: <number>,
  }
}

Error response:

WFE: String message with 500 response code

OM: { message: <error-message>, data: null, metadata: {} } with response code 400 for bad inputs and 500 for internal error.


WFE Method OM Replacement Method
POST /tasks/search GET /tasks

⚠ Please use the OM search documentation as a reference when translating search parameters between these two endpoints.

Success response:

WFE: [{ ...task1 }, { ...task2 }, ...]

OM:

{
  message: <success-message>,
  data: [{ ...task1 }, { ...task2 }, ...],
  metadata: {
    skip: <number>,
    limit: <number>,
    nextPageSkip: <null | number>,
    previousPageSkip: <null | number>,
    total: <number>,
    currentPageSize: <number>,
  }
}

Error response:

WFE: String message with 500 response code

OM: { message: <error-message>, data: null, metadata: {} } with response code 400 for bad inputs and 500 for internal error.